DOCSP-41992 Upgrade versions #152
Conversation
✅ Deploy Preview for docs-php-library ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
lindseymoore
requested review from
a team and
alcaeus
and removed request for
a team
source/upgrade.txt
Outdated
| .. code-block:: bash | ||
|
|
||
| composer require mongodb/mongodb:<version-number> | ||
|
|
||
| Installation instructions for the ``mongodb`` extension may be found in the | ||
| :php:`PHP.net documentation <manual/en/mongodb.installation.php>`. |
There was a problem hiding this comment.
We should actually list the instructions on how to install the extension as well. This can be done by running the following:
pecl upgrade mongodb-<version-number>
The note about the PHP documentation can be amended to read "Detailed installation instructions [...]"
We should highlight that while the major and minor version numbers of the extension and library are in sync, the patch version is not.
There was a problem hiding this comment.
Added explanation about upgrading for different versions. Let me know what you think. thanks!
|
|
||
| .. _php-breaking-changes: | ||
|
|
||
| Breaking Changes |
There was a problem hiding this comment.
A couple of notes here:
- We don't consider dropping support for a server version a breaking change, otherwise it would only be done in a major version. When we drop support for a server version, it has been out of official support for several years.
- Deprecations are not considered breaking changes - rather is it a way to announce an upcoming breaking change that will be made in a future major version.
- Upgrading the extension requirement or PHP requirements are also not breaking changes, as composer's dependency resolution will refuse to install a version of the library that isn't compatible with the installed extension version or the installed PHP version.
To summarise, this section should mention that we will make breaking changes only in a new major version, and we're also providing an upgrade file to go along with that version, along with deprecating any functionality to be removed. For example, we're currently working on version 2.0 of the extension, and the corresponding upgrade file lists everything that is removed. Note that this is a work in progress and should not yet be added to the docs.
We can list dropping support for MongoDB 3.6 in version 1.20 as a breaking change, but the other changes listed are not breaking changes in a traditional sense and should be removed.
There was a problem hiding this comment.
I concur with reserving the term "breaking changes" for the driver API and thus new major versions; however, we should make sure all driver docs are on the same page here.
Removing support for EOL server and PHP versions is something communicated in release notes, and DBX also has a policy of announcing server compatibility changes in advance.
There was a problem hiding this comment.
I will remove all the deprecation notes other than the dropped support for MongoDB Server 3.6 for Version 1.20.
Once version 2.0 is released, we can add a note about upgrade files, as there are no other upgrade files for current versions out (the last one I see was for upgrading to 1.5 which is now the oldest relevant version according to compatibility table).
Let me know if this looks good, thanks!
Pull Request Info
PR Reviewing Guidelines
JIRA - https://jira.mongodb.org/browse/DOCSP-41992
Staging - https://deploy-preview-152--docs-php-library.netlify.app/upgrade/
Self-Review Checklist